Help/Tutorials/Getting-Started/Scheduling Events.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <title></title>
   7 <meta name="Generator" content="Cocoa HTML Writer">
   8 <meta name="CocoaVersion" content="824.44">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #000000}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #bf0000}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #0000bf}
  17 p.p8 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; color: #0020de}
  18 span.s1 {color: #0030dd}
  19 span.s2 {color: #0000bf}
  20 span.s3 {color: #606060}
  21 span.s4 {font: 9.0px Monaco}
  22 span.s5 {font: 9.0px Monaco; color: #606060}
  23 span.s6 {color: #000000}
  24 span.s7 {font: 12.0px Helvetica; color: #0020de}
  25 span.s8 {color: #0000ff}
  26 span.s9 {color: #0039cf}
  27 span.Apple-tab-span {white-space:pre}
  28 </style>
  29 </head>
  30 <body>
  31 <p class="p1"><b>Scheduling Events</b></p>
  32 <p class="p2"><br></p>
  33 <p class="p3">Music happens over time, and to make effective music, it's necessary to control when things happen. In SuperCollider, this is done by scheduling things on clocks.</p>
  34 <p class="p2"><br></p>
  35 <p class="p4"><b>Clocks</b></p>
  36 <p class="p2"><br></p>
  37 <p class="p3">A clock in SuperCollider has two major functions. It knows what time it is, and it knows what time things are supposed to happen, so that it can wake them up at just the right time.</p>
  38 <p class="p2"><br></p>
  39 <p class="p3">Musical sequencing will usually use <a href="../../Scheduling/TempoClock.html"><span class="s1">TempoClock</span></a>, because you can change its tempo and it is also aware of meter changes. Two other kinds of clock exist: <a href="../../Scheduling/SystemClock.html"><span class="s1">SystemClock</span></a>, which always runs in seconds, and <a href="../../Scheduling/AppClock.html"><span class="s1">AppClock</span></a>, which also runs in seconds but has a lower system priority (so it is better for graphic updates and other activities that are not time critical).</p>
  40 <p class="p2"><br></p>
  41 <p class="p4"><b>Scheduling</b></p>
  42 <p class="p2"><br></p>
  43 <p class="p3">Scheduling means to tell the clock to execute something at some time in the future. So, you need to have the thing to schedule, and a number indicating the time.</p>
  44 <p class="p2"><br></p>
  45 <p class="p3">Let's have SuperCollider say hello, 5 seconds from now.</p>
  46 <p class="p2"><br></p>
  47 <p class="p5"><span class="s2">SystemClock</span>.sched(5, { <span class="s3">"hello"</span>.postln });</p>
  48 <p class="p2"><br></p>
  49 <p class="p3">Notice that when you do this, 'SystemClock' prints immediately. Every time you run something in SuperCollider, it has to return a value right away; the method's return value is the clock. Before returning, however, the clock 'remembers' the function, and that you wanted it to run 5 seconds later. And indeed, 'hello' appears in the post window, right on cue. <span class="s4">{ </span><span class="s5">"hello"</span><span class="s4">.postln }</span> is an <i>asynchronous</i> action: it runs <i>after</i> its code block has already returned.</p>
  50 <p class="p2"><br></p>
  51 <p class="p3"><b>sched</b> does <i>relative</i> scheduling. The actual time when the function runs is <i>x</i> seconds (or beats, for TempoClock) later than the time the .sched call occurred. It is also possible to schedule for an exact time point, provided you know what time it is on the clock. <b>schedAbs</b> handles <i>absolute</i> scheduling.</p>
  52 <p class="p2"><br></p>
  53 <p class="p5">(</p>
  54 <p class="p5"><span class="s2">var</span><span class="Apple-tab-span">  </span>timeNow = <span class="s2">TempoClock</span>.default.beats;</p>
  55 <p class="p5"><span class="s3">"Time is now: "</span>.post; timeNow.postln;</p>
  56 <p class="p5"><span class="s3">"Scheduling for: "</span>.post; (timeNow + 5).postln;</p>
  57 <p class="p5"><span class="s2">TempoClock</span>.default.schedAbs(timeNow + 5,</p>
  58 <p class="p5"><span class="Apple-tab-span">     </span>{ <span class="s3">"Time is later: "</span>.post; <span class="s2">thisThread</span>.clock.beats.postln; <span class="s2">nil</span> });</p>
  59 <p class="p5">)</p>
  60 <p class="p2"><br></p>
  61 <p class="p3">Note that we have moved to TempoClock, since this is the most commonly used. While there is only one SystemClock, there can be many TempoClocks all running at different speeds, if need be. One TempoClock is the default, accessed by <b>TempoClock.default</b> -- we will use this throughout. (To save typing, you may wish to assign a TempoClock to a variable, for instance, <b>t = TempoClock.default</b>.)</p>
  62 <p class="p2"><br></p>
  63 <p class="p3">For fun, change the tempo and run the last example again:</p>
  64 <p class="p2"><br></p>
  65 <p class="p5">(</p>
  66 <p class="p5"><span class="s2">var</span><span class="Apple-tab-span">  </span>timeNow;</p>
  67 <p class="p6"><span class="s2">TempoClock</span><span class="s6">.default.tempo = 2;<span class="Apple-tab-span">       </span></span>// 2 beats/sec, or 120 BPM</p>
  68 <p class="p5">timeNow = <span class="s2">TempoClock</span>.default.beats;</p>
  69 <p class="p5"><span class="s3">"Time is now: "</span>.post; timeNow.postln;</p>
  70 <p class="p5"><span class="s3">"Scheduling for: "</span>.post; (timeNow + 5).postln;</p>
  71 <p class="p5"><span class="s2">TempoClock</span>.default.schedAbs(timeNow + 5,</p>
  72 <p class="p5"><span class="Apple-tab-span">     </span>{ <span class="s3">"Time is later: "</span>.post; <span class="s2">thisThread</span>.clock.beats.postln; <span class="s2">nil</span> });</p>
  73 <p class="p5">)</p>
  74 <p class="p2"><br></p>
  75 <p class="p3">Notice that the 'Time is later' message shows up after a shorter delay, but the difference between the two times is still 5.</p>
  76 <p class="p2"><br></p>
  77 <p class="p4"><b>What time is it?</b></p>
  78 <p class="p2"><br></p>
  79 <p class="p3">Inside a scheduled function, you might want to know which clock is running the function. <b>thisThread.clock</b> tells you this -- don't worry for now about how it knows, just know that you can use this to find out.</p>
  80 <p class="p2"><br></p>
  81 <p class="p3">Once you know the clock, you can find out what time it is using <b>beats</b>:</p>
  82 <p class="p2"><br></p>
  83 <p class="p7">SystemClock<span class="s6">.beats;</span></p>
  84 <p class="p5"><span class="s2">TempoClock</span>.default.beats;</p>
  85 <p class="p7">AppClock<span class="s6">.beats;</span></p>
  86 <p class="p5"><span class="s2">thisThread</span>.clock.beats;</p>
  87 <p class="p2"><br></p>
  88 <p class="p4"><b>What can you schedule?</b></p>
  89 <p class="p2"><br></p>
  90 <p class="p3">Suppose we schedule "hello" by itself.</p>
  91 <p class="p2"><br></p>
  92 <p class="p5"><span class="s2">TempoClock</span>.default.sched(5, <span class="s3">"hello"</span>);</p>
  93 <p class="p2"><br></p>
  94 <p class="p3">Nothing happens. That's because "hello" is just a value -- it doesn't do anything. The lesson is that it makes sense to schedule objects that will <i>take some action</i>.</p>
  95 <p class="p2"><br></p>
  96 <p class="p3">Function</p>
  97 <p class="p3">Routine</p>
  98 <p class="p3">Task</p>
  99 <p class="p2"><br></p>
 100 <p class="p3">Routines and Tasks will be covered in the next section, and Functions we have already seen. There are some others, but these are the best starting point.</p>
 101 <p class="p2"><br></p>
 102 <p class="p4"><b>Caution</b></p>
 103 <p class="p2"><br></p>
 104 <p class="p3">If you schedule function that returns a number, the clock will treat that number as the amount of time before running the function again.</p>
 105 <p class="p2"><br></p>
 106 <p class="p6">// fires many times (but looks like it should fire just once)</p>
 107 <p class="p5"><span class="s2">TempoClock</span>.default.sched(1, { rrand(1, 3).postln; });</p>
 108 <p class="p2"><br></p>
 109 <p class="p3">This will keep going forever, until you stop it with cmd-.</p>
 110 <p class="p2"><br></p>
 111 <p class="p3">If you want the function to run only once, make sure to end the function with 'nil':</p>
 112 <p class="p2"><br></p>
 113 <p class="p6">// fires once</p>
 114 <p class="p5"><span class="s2">TempoClock</span>.default.sched(1, { rrand(1, 3).postln; <span class="s2">nil</span> });</p>
 115 <p class="p2"><br></p>
 116 <p class="p3">It's easy to return a number by mistake, and get an ongoing activity when you wanted a one-shot action.</p>
 117 <p class="p2"><br></p>
 118 <p class="p3">If that number happens to be 0, or negative, something worse happens. The function will run again immediately. And, if the number is always 0, it creates an infinite loop that can lock up SuperCollider.</p>
 119 <p class="p2"><br></p>
 120 <p class="p3">That shouldn't scare you off of scheduling -- this is less likely to happen with Routines and Tasks, which you will use more often. But you should be aware of it.</p>
 121 <p class="p2"><br></p>
 122 <p class="p8"><span class="s6">For more:<span class="Apple-tab-span">   </span><a href="../../Scheduling/SystemClock.html"><span class="s7">SystemClock</span></a><span class="Apple-tab-span"> </span><a href="../../Scheduling/TempoClock.html"><span class="s7">TempoClock</span></a><span class="Apple-tab-span">   </span><a href="../../Scheduling/AppClock.html"><span class="s7">AppClock</span></a></span></p>
 123 <p class="p8"><span class="s6"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><a href="../../Core/Kernel/Function.html"><span class="s7">Function</span></a></span></p>
 124 <p class="p2"><br></p>
 125 <p class="p3">____________________</p>
 126 <p class="p2"><br></p>
 127 <p class="p3">This document is part of the tutorial <b>Getting Started With SuperCollider</b>.</p>
 128 <p class="p2"><br></p>
 129 <p class="p3">Click here to go on to the next section: <a href="Sequencing with Routines and Tasks.html"><span class="s8">Sequencing with Routines and Tasks</span></a></p>
 130 <p class="p2"><br></p>
 131 <p class="p3">Click here to return to the table of Contents: <a href="Getting Started With SC.html"><span class="s9">Getting Started With SC</span></a></p>
 132 </body>
 133 </html>